home *** CD-ROM | disk | FTP | other *** search
/ X User Tools / X User Tools (O'Reilly and Associates)(1994).ISO / sun4c / archive / tcltk.z / tcltk / man / cat3 / Interp.3 < prev    next >
Text File  |  1994-09-20  |  7KB  |  199 lines
  1.  
  2.  
  3.  
  4. Tcl_Interp(3)        Tcl Library Procedures
  5.  
  6.  
  7.  
  8. _________________________________________________________________
  9.  
  10. NAME
  11.      Tcl_Interp - client-visible fields of interpreter structures
  12.  
  13. SYNOPSIS
  14.      #include <tcl.h>
  15.  
  16.      typedef struct {
  17.           char *_r_e_s_u_l_t;
  18.           Tcl_FreeProc *_f_r_e_e_P_r_o_c;
  19.           int _e_r_r_o_r_L_i_n_e;
  20.      } Tcl_Interp;
  21.  
  22.      typedef void Tcl_FreeProc(char *_b_l_o_c_k_P_t_r);
  23. _________________________________________________________________
  24.  
  25.  
  26. DESCRIPTION
  27.      The  Tcl_CreateInterp  procedure  returns  a  pointer  to  a
  28.      Tcl_Interp  structure.   This  pointer  is  then passed into
  29.      other Tcl procedures to process commands in the  interpreter
  30.      and  perform  other  operations  on the interpreter.  Inter-
  31.      preter structures contain many many fields that are used  by
  32.      Tcl,  but  only  three  that  may  be  accessed  by clients:
  33.      _r_e_s_u_l_t, _f_r_e_e_P_r_o_c, and _e_r_r_o_r_L_i_n_e.
  34.  
  35.      The _r_e_s_u_l_t and _f_r_e_e_P_r_o_c fields are used to return results or
  36.      error  messages from commands.  This information is returned
  37.      by command procedures back to Tcl_Eval, and by Tcl_Eval back
  38.      to  its callers.  The _r_e_s_u_l_t field points to the string that
  39.      represents the result or error  message,  and  the  _f_r_e_e_P_r_o_c
  40.      field  tells  how  to  dispose of the storage for the string
  41.      when it isn't needed anymore.  The easiest way  for  command
  42.      procedures  to manipulate these fields is to call procedures
  43.      like Tcl_SetResult or Tcl_AppendResult;  they will hide  all
  44.      the  details  of managing the fields.  The description below
  45.      is for those procedures that manipulate the fields directly.
  46.  
  47.      Whenever a command procedure returns, it  must  ensure  that
  48.      the  _r_e_s_u_l_t  field  of  its interpreter points to the string
  49.      being returned by the command.  The _r_e_s_u_l_t field must always
  50.      point  to  a valid string.  If a command wishes to return no
  51.      result then _i_n_t_e_r_p->_r_e_s_u_l_t should point to an empty  string.
  52.      Normally,  results  are  assumed to be statically allocated,
  53.      which means that the contents will  not  change  before  the
  54.      next time Tcl_Eval is called or some other command procedure
  55.      is invoked.  In this case, the _f_r_e_e_P_r_o_c field must be  zero.
  56.      Alternatively,  a command procedure may dynamically allocate
  57.      its return value (e.g. using malloc) and store a pointer  to
  58.      it  in  _i_n_t_e_r_p->_r_e_s_u_l_t.  In this case, the command procedure
  59.      must also set _i_n_t_e_r_p->_f_r_e_e_P_r_o_c to the address of a procedure
  60.  
  61.  
  62.  
  63. Tcl                                                             1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. Tcl_Interp(3)        Tcl Library Procedures
  71.  
  72.  
  73.  
  74.      that can free the value (usually free).  If _i_n_t_e_r_p->_f_r_e_e_P_r_o_c
  75.      is non-zero, then Tcl will call _f_r_e_e_P_r_o_c to free  the  space
  76.      pointed to by _i_n_t_e_r_p->_r_e_s_u_l_t before it invokes the next com-
  77.      mand.  If a client procedure overwrites _i_n_t_e_r_p->_r_e_s_u_l_t  when
  78.      _i_n_t_e_r_p->_f_r_e_e_P_r_o_c  is  non-zero,  then  it is responsible for
  79.      calling  _f_r_e_e_P_r_o_c  to  free  the  old  _i_n_t_e_r_p->_r_e_s_u_l_t   (the
  80.      Tcl_FreeResult macro should be used for this purpose).
  81.  
  82.      _F_r_e_e_P_r_o_c should have arguments and  result  that  match  the
  83.      Tcl_FreeProc  declaration above:  it receives a single argu-
  84.      ment which is a pointer to the result  value  to  free.   In
  85.      most  applications free is the only non-zero value ever used
  86.      for _f_r_e_e_P_r_o_c.  However, an application may store a different
  87.      procedure  address  in _f_r_e_e_P_r_o_c in order to use an alternate
  88.      memory allocator or in order to do other  cleanup  when  the
  89.      result memory is freed.
  90.  
  91.      As part of processing  each  command,  Tcl_Eval  initializes
  92.      _i_n_t_e_r_p->_r_e_s_u_l_t  and _i_n_t_e_r_p->_f_r_e_e_P_r_o_c just before calling the
  93.      command procedure for the command.  The _f_r_e_e_P_r_o_c field  will
  94.      be  initialized to zero, and _i_n_t_e_r_p->_r_e_s_u_l_t will point to an
  95.      empty string.  Commands that do not  return  any  value  can
  96.      simply  leave  the  fields  alone.   Furthermore,  the empty
  97.      string pointed to by _r_e_s_u_l_t is actually part of an array  of
  98.      TCL_RESULT_SIZE  characters  (approximately 200).  If a com-
  99.      mand wishes to return a short string, it can simply copy  it
  100.      to  the  area  pointed to by _i_n_t_e_r_p->_r_e_s_u_l_t.  Or, it can use
  101.      the sprintf procedure to generate a short result  string  at
  102.      the location pointed to by _i_n_t_e_r_p->_r_e_s_u_l_t.
  103.  
  104.      It is a general convention in  Tcl-based  applications  that
  105.      the  result of an interpreter is normally in the initialized
  106.      state described in the previous paragraph.  Procedures  that
  107.      manipulate  an  interpreter's  result  (e.g. by returning an
  108.      error) will generally assume that the result has  been  ini-
  109.      tialized  when the procedure is called.  If such a procedure
  110.      is to be called after the  result  has  been  changed,  then
  111.      Tcl_ResetResult  should  be called first to reset the result
  112.      to its initialized state.
  113.  
  114.      The _e_r_r_o_r_L_i_n_e field is valid only after Tcl_Eval  returns  a
  115.      TCL_ERROR  return  code.   In  this  situation the _e_r_r_o_r_L_i_n_e
  116.      field identifies the line number of the command  being  exe-
  117.      cuted  when  the error occurred.  The line numbers are rela-
  118.      tive to the command being executed:  1 means the first  line
  119.      of  the command passed to Tcl_Eval, 2 means the second line,
  120.      and so on.  The _e_r_r_o_r_L_i_n_e field is typically  used  in  con-
  121.      junction  with  Tcl_AddErrorInfo to report information about
  122.      where an error occurred.  _E_r_r_o_r_L_i_n_e should not  normally  be
  123.      modified except by Tcl_Eval.
  124.  
  125.  
  126.  
  127.  
  128.  
  129. Tcl                                                             2
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. Tcl_Interp(3)        Tcl Library Procedures
  137.  
  138.  
  139.  
  140. KEYWORDS
  141.      free, initialized, interpreter, malloc, result
  142.  
  143.  
  144.  
  145.  
  146.  
  147.  
  148.  
  149.  
  150.  
  151.  
  152.  
  153.  
  154.  
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195. Tcl                                                             3
  196.  
  197.  
  198.  
  199.